time skipping supports max skip, polling, describe by feiyang3cat · Pull Request #835 · temporalio/api

feiyang3cat · 2026-07-19T21:07:05Z

What changed?

add a max skip field to TimeSkippingConfig
add TimeSkippingInfo to DescribeWorkflowExecution (contains virtual current time and time-skipping runtime status)
add PollWorkflowExecutionTimeSkipping for fast-forward completion
comment refinements: remove the workflow keyword from time-skipping message comments under the common path
change fast_forward from a duration field to a message with both duration and id

Breaking changes
Change #5

feiyang3cat · 2026-07-20T00:31:37Z

    google.protobuf.Timestamp fast_forward_target_time = 2;
+
+    // The initial skip count. It only propagates across a chain of runs within the same execution.
+    int32 initial_skip_count = 3;


for reviewers: this shall be propagated so that we can stop workflow retry as workflow retry generates a new run instead retrying within the same run

feiyang3cat · 2026-07-20T04:21:17Z

+    //
+    // If this field is not set, the server applies a large default value (e.g. 100). The default can
+    // be changed through dynamic config, and is overridden by this field when set.
+    int32 max_skip_per_session = 4;


we use a per_session max_skip instead of a total/delta max_skip to make this feature easy

the unneeded complexity introduced by other options:

total: when the value is updated, both the client and server need to read current skip number to decide if the new value is valid and we may need to expose the current skip number

delta: as we set a default value when the field is not set, if the user set TSC multiple times, delta may silently accumulate the total number to a large number

feiyang3cat · 2026-07-20T16:16:12Z

+        // The fast-forward that was active when the poll started reached its target time and completed.
+        RESULT_FAST_FORWARD_COMPLETED = 2;
+        // No fast-forward was in progress when the poll started, so there was nothing to wait for.
+        RESULT_NO_PENDING_FAST_FORWARD = 3;


also need to add an result of workflow end (status = completed/failed/canceled/TERMINATED/TIMED_OUT)
but we need the whole execution (a chain of runs) to end instead of a single run's status

simvlad · 2026-07-20T18:25:41Z

+
+message PollWorkflowExecutionTimeSkippingResponse {
+    enum Result {
+        // The poll timed out server-side before any time-skipping state change occurred to fast forward.


Sound like this should be different than RESULT_UNSPECIFIED, maybe RESULT_TIMED_OUT?

simvlad · 2026-07-20T18:31:37Z

+// In-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations, etc.
+// User timers are not classified as in-flight work and will be skipped over; the virtual clock may also skip to the
+// time point of the registered fast-forward when there is no in-flight work.
+// Every time time is skipped, the skip count is incremented by one; max_skip_per_session bounds the number of skips allowed within a single time-skipping session.


time time :)

feiyang3cat · 2026-07-21T00:44:30Z

    google.protobuf.Duration fast_forward = 2;

+    // A client-supplied ID that must be set together with `fast_forward`. It is used to poll for
+    // fast-forward completion via PollWorkflowExecutionTimeSkipping.


for reviewers: explicitly making this id required if fast_forward is used for simplicity

Is there a reason not to make it optional? The SDK only needs this to wait on the result of a FF, and it doesn't always need to do that.

I think both ways work:

server doesn't allow empty ff-id, and if users don't want to wait on it they can set a default id or random id

server allow setting empty ff-id, and we need to define a sound behavior for polling with ff-id empty. I think the simplest way is we don't allow polling an empty ff-id

2.1. so polling with ff-id in the request will have an argument error

2.2. polling with a valid ff-id but the current ff-id is empty will return ff-id not matching

2.3. in comments we indicate if users want to poll for the ff they need to set a ff-id for it

feiyang3cat · 2026-07-21T23:31:43Z

+    // If the execution is actively trying to skip time automatically when there is a chance,
+    // this field will be set to true. If time has stopped skipping either by fast-forward completion,
+    // max skip allowed checking, or user configuration, it will be false.
+    bool is_running = 2;


@tegan-temporal

…ments

…t-forward verification

…ed distinctions between types, which reduces complexity.

feiyang3cat · 2026-07-28T00:35:52Z

+    FastForwardConfig fast_forward_config = 2;

    // By default, executions started by another execution (e.g. a child workflow of a parent workflow or
-    // a schedule with the timeskipping policy enabled), inherit the "enabled" flag and skip time when possible.


refine the comment: this is about config propagation for different executions (not different runs within the same execution

feiyang3cat · 2026-07-28T19:07:06Z

    // This flag disables that inheritance.
    bool disable_propagation = 3;
+
+    // The maximum number of skips allowed every time this field is updated. It protects the execution from


@GregoryTravis

GregoryTravis · 2026-07-21T15:00:27Z

    google.protobuf.Duration fast_forward = 2;

+    // A client-supplied ID that must be set together with `fast_forward`. It is used to poll for
+    // fast-forward completion via PollWorkflowExecutionTimeSkipping.


Is there a reason not to make it optional? The SDK only needs this to wait on the result of a FF, and it doesn't always need to do that.

GregoryTravis · 2026-07-21T15:15:21Z

-        // The fast-forward that was active when the poll started reached its target time and completed.
+        // The poll timed out server-side before the fast-forward completed. The caller may poll again.
+        RESULT_POLL_TIMEOUT = 1;
+        // The fast-forward identified by the request's `fast_forward_id` reached its target time and completed.


Maybe repeat here that the server only keeps the most recently started FF ID.

GregoryTravis · 2026-07-28T19:15:22Z

+    // max_session_skip_count, time skipping stops. Whenever this config field is updated, the accumulated
+    // skip count is cleared, marking the start of a new session.
+    // For an execution with a chain of runs (retry, cron, continue-as-new), the count is accumulated
+    // across all runs within the same session.


I wondering about an edge case where you execute a single fast forward, but across e.g. 3 retries: does this count as 3 skips against the max, or just one?

If it's just one, perhaps add something like "multiple retries during a single fast-forward only count as one skip".

it will count as 3, and the default value right now is 250. I think it will be fine users can change the default value or override the value using api. But indeed it is hard for user to estimate the number accurately if they don't want to study the internal server timer mechanism so it will be rough number.

How about a workflow that does 3 multiple sequential sleeps? Does each one count against the max?

I realize that this field is probably not one that users will set very often, but I want to figure out a way to write a test for it, if the SDK is going to expose it.

Or perhaps it is enough to test this by setting the field, and reading the configuration back and confirming it? Rather than verifying server behavior?

skipping 3 sleeps will count as 3. server won't skip multiple timers at each skip.

I agree that users most of the time don't need to feel the existence of this option. And even if this max skip takes effect, they may not want to set this field but to figure out if their tests have unlimited retires.

feiyang3cat commented Jul 20, 2026

View reviewed changes

feiyang3cat force-pushed the vts-maxskip-poll branch from 085a333 to 67f341b Compare July 20, 2026 01:21

feiyang3cat changed the title ~~add max_skip_count and change comments of TimeSkippingConfig~~ time skipping supports max skip, polling, describe Jul 20, 2026

feiyang3cat commented Jul 20, 2026

View reviewed changes

GregoryTravis approved these changes Jul 20, 2026

View reviewed changes

simvlad reviewed Jul 20, 2026

View reviewed changes

feiyang3cat force-pushed the vts-maxskip-poll branch 5 times, most recently from 2a371d8 to dd493a2 Compare July 21, 2026 00:41

feiyang3cat commented Jul 21, 2026

View reviewed changes

feiyang3cat force-pushed the vts-maxskip-poll branch from dd493a2 to b4113e7 Compare July 21, 2026 01:23

feiyang3cat commented Jul 21, 2026

View reviewed changes

feiyang3cat force-pushed the vts-maxskip-poll branch 3 times, most recently from d9062aa to 226b1a5 Compare July 23, 2026 01:39

feiyang3cat added 11 commits July 23, 2026 15:34

add max_skip_count and change comments of TimeSkippingConfig

cbcf90d

add TimeSkippingInfo to WorkflowExecutionExtendedInfo, add poll api

310f708

add initial_skip_count to TimeSkippingStatePropagation and refine com…

9bba293

…ments

rename PollWorkflowExecutionTimeSkippingResponse fields

746b497

rename max_skip_per_session, add RESULT_WORKFLOW_ENDED

6330085

add fast_forward_id, and other runtime fields to TimeSkippingInfo

fe73888

delete update_time so that we don't mislead users to use time for fas…

186760c

…t-forward verification

change comments of update time in update wf options

e08d564

consolidated the Result types — no need to maintain overly fine-grain…

bea40da

…ed distinctions between types, which reduces complexity.

similify poll result

aacade5

add TimeSkippingStopReason

588c15b

feiyang3cat force-pushed the vts-maxskip-poll branch from 226b1a5 to 588c15b Compare July 23, 2026 22:34

feiyang3cat added 2 commits July 23, 2026 15:42

change field numbers

12228b6

delete reason

02f4001

feiyang3cat force-pushed the vts-maxskip-poll branch from a89ee5e to 02f4001 Compare July 23, 2026 23:33

remodel FastForwardConfig

111f563

feiyang3cat force-pushed the vts-maxskip-poll branch from a373f49 to 111f563 Compare July 24, 2026 18:42

feiyang3cat added 5 commits July 25, 2026 18:47

refine comments of max_session_skip_count

803ddfe

udpate TimeSkippingInfo

8427b6c

add effective config to describe workflow

ba08f2b

refine comments

95f7382

udpate PollWorkflowExecutionTimeSkipping

87a94c3

feiyang3cat marked this pull request as ready for review July 26, 2026 21:51

feiyang3cat requested review from a team July 26, 2026 21:51

feiyang3cat force-pushed the vts-maxskip-poll branch from 29f4ec6 to 4c38398 Compare July 26, 2026 22:21

feiyang3cat mentioned this pull request Jul 26, 2026

add features of describe, max skip, and poll fast-forward completion to time skipping temporalio/temporal#11220

Draft

feiyang3cat force-pushed the vts-maxskip-poll branch 2 times, most recently from 5bf50f9 to 134dd43 Compare July 26, 2026 23:00

refine comments

d01e17f

feiyang3cat force-pushed the vts-maxskip-poll branch from 134dd43 to d01e17f Compare July 26, 2026 23:02

feiyang3cat commented Jul 28, 2026

View reviewed changes

GregoryTravis reviewed Jul 28, 2026

View reviewed changes

Uh oh!

Conversation

feiyang3cat commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

feiyang3cat Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

feiyang3cat Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feiyang3cat commented Jul 19, 2026 •

edited

Loading

feiyang3cat Jul 29, 2026 •

edited

Loading

feiyang3cat Jul 28, 2026 •

edited

Loading